home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kuniqueapplication.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  7.4 KB  |  222 lines
  1. /* This file is part of the KDE libraries
  2.     Copyright (c) 1999 Preston Brown <pbrown@kde.org>
  3.     Copyright (c) 2000-2001 Waldo Bastian <bastian@kde.org>
  4.  
  5.     This library is free software; you can redistribute it and/or
  6.     modify it under the terms of the GNU Library General Public
  7.     License as published by the Free Software Foundation; either
  8.     version 2 of the License, or (at your option) any later version.
  9.  
  10.     This library is distributed in the hope that it will be useful,
  11.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  12.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13.     Library General Public License for more details.
  14.  
  15.     You should have received a copy of the GNU Library General Public License
  16.     along with this library; see the file COPYING.LIB.  If not, write to
  17.     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18.     Boston, MA 02110-1301, USA.
  19. */
  20.  
  21. #ifndef _KUNIQUEAPP_H
  22. #define _KUNIQUEAPP_H
  23.  
  24. #include <kapplication.h>
  25. #include <dcopobject.h>
  26.  
  27. class KUniqueApplicationPrivate;
  28.  
  29. /**
  30.  * Maintains only a single
  31.  * instance of a running application at a time.
  32.  *
  33.  * If another instance
  34.  * is started, it will determine (via DCOP) whether it is the first instance
  35.  * or a second instance.  If it is a second instance, it will forward on
  36.  * the information to the first instance and then quit.
  37.  *
  38.  * The .desktop file for the application should state X-DCOP-ServiceType=Unique,
  39.  * see kapplication.h
  40.  *
  41.  * If your application is used to open files, it should also support the --tempfile
  42.  * option (see KCmdLineArgs::addTempFileOption()), to delete tempfiles after use.
  43.  * Add X-KDE-HasTempFileOption=true to the .desktop file to indicate this.
  44.  *
  45.  * @see KApplication DCOPObject
  46.  * @author Preston Brown <pbrown@kde.org>
  47.  */
  48. class KDECORE_EXPORT KUniqueApplication : public KApplication, public DCOPObject
  49. {
  50.   Q_OBJECT
  51. public:
  52.   /**
  53.    * Constructor. Takes command line arguments from KCmdLineArgs
  54.    *
  55.    * @param allowStyles Set to false to disable the loading on plugin based
  56.    * styles. This is only useful to applications that do not display a GUI
  57.    * normally. If you do create an application with @p allowStyles set to false
  58.    * it normally runs in the background but under special circumstances
  59.    * displays widgets.  Call KApplication::enableStyles() before 
  60.    * displaying any widgets.
  61.    * @param GUIenabled Set to false to disable all GUI stuff. This implies
  62.    * no styles either.
  63.    * @param configUnique If true, the uniqueness of the application will
  64.    *                 depend on the value of the "MultipleInstances"
  65.    *                 key in the "KDE" group of the application config file.
  66.    */
  67.   KUniqueApplication( bool allowStyles=true,
  68.               bool GUIenabled=true,
  69.               bool configUnique=false);
  70.  
  71. #ifdef Q_WS_X11
  72.   /**
  73.    * Constructor. Takes command line arguments from KCmdLineArgs
  74.    *
  75.    * @param display Will be passed to Qt as the X display. The display
  76.    * must be valid and already opened.
  77.    * @param visual Pointer to the X11 visual that should be used by the
  78.    * application. If NULL, the default visual will be used instead.
  79.    * @param colormap The colormap that should be used by the application.
  80.    * If 0, the default colormap will be used instead.
  81.    * @param allowStyles Set to false to disable the loading on plugin based
  82.    * styles. This is only useful to applications that do not display a GUI
  83.    * normally. If you do create an application with @p allowStyles set to false
  84.    * it normally runs in the background but under special circumstances
  85.    * displays widgets.  Call KApplication::enableStyles() before 
  86.    * displaying any widgets.
  87.    * @param configUnique If true, the uniqueness of the application will
  88.    *                 depend on the value of the "MultipleInstances"
  89.    *                 key in the "KDE" group of the application config file.
  90.    * @since KDE 3.3
  91.    */
  92.   KUniqueApplication( Display *display,
  93.               Qt::HANDLE visual=0,
  94.               Qt::HANDLE colormap=0,
  95.               bool allowStyles=true,
  96.               bool configUnique=false);
  97. #endif
  98.  
  99.   /**
  100.    * Adds command line options specific for KUniqueApplication.
  101.    *
  102.    * Should be called before calling KUniqueApplication constructor
  103.    * and / or start().
  104.    */
  105.   static void addCmdLineOptions();
  106.  
  107.   /**
  108.    * Forks and registers with dcop.
  109.    *
  110.    * The command line arguments are being sent via DCOP to newInstance()
  111.    * and will be received once the application enters the event loop.
  112.    *
  113.    * Typically this is used like:
  114.    * \code
  115.    * int main(int argc, char **argv) {
  116.    *    KAboutData about("myappname", "myAppName", .....);
  117.    *    KCmdLineArgs::init(argc, argv, &about);
  118.    *    KCmdLineArgs::addCmdLineOptions( myCmdOptions );
  119.    *    KUniqueApplication::addCmdLineOptions();
  120.    *
  121.    *    if (!KUniqueApplication::start()) {
  122.    *       fprintf(stderr, "myAppName is already running!\n");
  123.    *       exit(0);
  124.    *    }
  125.    *    KUniqueApplication a;
  126.    *    a.exec();
  127.    * }
  128.    * \endcode
  129.    * Note that it's not necessary to call start() explicitly. It will be
  130.    * called automatically before creating KUniqueApplication if it hasn't
  131.    * been called yet, without any performance impact.
  132.    *
  133.    * @return true if registration is successful.
  134.    *         false if another process was already running.
  135.    */
  136.   static bool start();
  137.  
  138.   /**
  139.    * Destructor
  140.    */
  141.   virtual ~KUniqueApplication();
  142.  
  143.   /**
  144.    * Dispatches any incoming DCOP message for a new instance.
  145.    *
  146.    * If it is not a request for a new instance, return false.
  147.    * Overloaded from DCOPObject to make sure that the application
  148.    * stays unique.
  149.    * @param fun DCOP function signature
  150.    * @param data the data for the arguments
  151.    * @param replyType the type of the reply value
  152.    * @param replyData the reply
  153.    * @see DCOPObject
  154.    */
  155.   bool process(const QCString &fun, const QByteArray &data,
  156.            QCString &replyType, QByteArray &replyData);
  157.  
  158.   /**
  159.    * Creates a new "instance" of the application.
  160.    *
  161.    * Usually this will involve making some calls into the GUI portion of your
  162.    * application asking for a new window to be created, possibly with
  163.    * some data already loaded based on the arguments received.
  164.    *
  165.    * Command line arguments have been passed to KCmdLineArgs before this
  166.    * function is called and can be checked in the usual way.
  167.    *
  168.    * The default implementation ensures the mainwindow of the already
  169.    * running instance is shown and activated if necessary. You should
  170.    * prefer using it from your overridden method instead of doing
  171.    * it directly.
  172.    * 
  173.    * Note that newInstance() is called also in the first started 
  174.    * application process.
  175.    *
  176.    * @return An exit value. The calling process will exit with this value.
  177.    */
  178.   virtual int newInstance();
  179.  
  180.   /**
  181.    * Returns whether newInstance() is being called while session
  182.    * restoration is in progress.
  183.    *
  184.    * @since KDE 3.3
  185.    */
  186.   bool restoringSession();
  187.   
  188.   /**
  189.    * @internal
  190.    */
  191.   static void setHandleAutoStarted();
  192.  
  193. private:
  194.   /**
  195.    * Delays the processing of a DCOP request.
  196.    */
  197.   void delayRequest(const QCString &fun, const QByteArray &data);
  198.  
  199. private slots:
  200.   /**
  201.    * Delayed processing of DCOP requests.
  202.    */
  203.   void processDelayed();
  204.  
  205.   void newInstanceNoFork();
  206.   
  207.   static KInstance* initHack( bool configUnique );
  208.  
  209. private:
  210.   static bool s_nofork;
  211.   static bool s_multipleInstances;
  212.   static bool s_uniqueTestDone;
  213.   static bool s_handleAutoStarted;
  214.  
  215. protected:
  216.   virtual void virtual_hook( int id, void* data );
  217. private:
  218.   KUniqueApplicationPrivate *d;
  219. };
  220.  
  221. #endif
  222.